feat(hosts): add Pi coding agent host adapter by NickyLam · Pull Request #25 · QoderAI/better-harness

NickyLam · 2026-07-30T02:38:36Z

Summary

Pi (pi.dev, @earendil-works/pi-coding-agent) can now run /better-harness as a first-class host: pi install <repo> discovers the skill and a /better-harness prompt template, and reviews on Pi gain real configured-asset and session evidence instead of unobserved lanes.

Why

Issue/Story: none — this follows the contribution table's invitation to "document and validate evidence support for another coding-agent host", using the recently added Qwen Code host as the structural template.
User or maintainer outcome: Pi users get durable HTML + Markdown reports backed by their own session transcripts and pi-package/skill/prompt inventory; previously Better Harness had no Pi support at all.

Traceability and Scope

Spec/ADR, if applicable: docs/adapters/README.md host-boundary contract (host differences enter only the matrix, configured-asset providers, session adapters, and output modes).
Acceptance criteria addressed: Pi row in the adapter matrix; --platform pi accepted across session-analysis, evidence-bundle, asset-baseline/integrity, task-loop, report-run, and agent-lint; pi install/pi -e discovery works from the repository root.
Canonical owners changed: scripts/agent-customize/providers/pi.mjs and scripts/session-analysis/platforms/pi.mjs (new), platform registration lists across scripts/, package.json (pi manifest, prompts/ packaging), prompts/better-harness.md, references/agent-customize/platforms/pi.md, adapter-matrix docs (en/zh), READMEs, CHANGELOG.
Explicit non-goals: no native MCP inventory for Pi (Pi has none; MCP arrives via extensions and stays extension-bound), no pi-package glob-filter/enable-state inventory, no docs/adapters/pi.md split (no split trigger met), no change to the Qoder runtime bundle contents.

Change Type

Feature

Test and Review Evidence

Check	Result
`npm test`	874/874 pass (baseline 867 + 7 new Pi tests)
`npm run pack:verify`	pass — npm 313 entries incl. `package/prompts/better-harness.md`; runtime zip 338 entries with `prompts/` correctly excluded
`node scripts/session-analysis.mjs sources --platform pi --workspace /private/tmp` (real local Pi data)	4 workspace-matching sessions discovered; cross-workspace transcripts rejected
`node scripts/session-analysis.mjs facts --platform pi ...`	`session-core-facts` with 2 candidates; no session-id or home-path leakage in output
`better-harness agent-customize inventory --provider pi` (real `~/.pi/agent`)	12 pi-package plugins across npm/git/extension-dir sources, 56 user skills, prompt commands, `AGENTS.md` rules
`better-harness harness evidence-bundle --platform pi --workspace <repo>`	`status: complete`; sessionEvidence/projectHarness/agentCustomize + lead all available
Pi's own `DefaultPackageManager.resolveExtensionSources(<repo>)` in an isolated agent dir	resolves exactly 1 skill (`better-harness`) and 1 prompt template (`better-harness.md`) from the `pi` manifest

Manual or visual evidence: session-format fixtures were derived from real Pi v3 JSONL transcripts and pi 0.83.0 source (session-manager.js slug rule, config.js env overrides), not from documentation alone.

Risk and Recovery

Compatibility and cross-platform impact: existing hosts unchanged (all pre-existing tests pass without behavioral edits; only usage strings, provider lists, and two frozen CLI-contract hashes moved). Windows session-dir slugs (\ and : replacement) are covered by unit tests.
Package, plugin, schema, or generated-file impact: npm package adds the pi manifest key, pi-package keyword, and prompts/; verify-pack enforces the new required entry and forbids prompts/ from the Qoder runtime bundle. No schema changes.
Rollback or recovery path: revert this single commit; no migrations or generated state.
Residual risk or unverified boundary: a full end-to-end /better-harness report run inside an interactive Pi session (model-driven) was not exercised; discovery, evidence collection, and bundle assembly were verified directly. Pi package manifest glob filters and per-resource enable state are declared unsupported rather than inventoried.

AI Involvement

Level: Generated
Human review and validation: contributor reviewed the full diff and ran the complete validation matrix above (test suite, pack verification, and smoke runs against real local Pi data).

Checklist

I followed AGENTS.md, CONTRIBUTING.md, and the relevant canonical-owner guidance.
The change is focused and does not include unrelated local or generated state.
Tests and documentation match the behavior actually delivered.
Markdown links were checked when documentation moved or changed.
Cross-platform behavior was considered for Windows, macOS, and Linux.
Package/runtime verification was run when shipped files or dependencies changed.
User-facing or compatibility changes are recorded in CHANGELOG.md.
I have the right to contribute this work under the repository's MIT License.

Copilot

Pull request overview

Adds first-class support for the Pi coding-agent host (pi.dev, @earendil-works/pi-coding-agent) by introducing a new Pi session-analysis adapter, a Pi agent-customize inventory provider, and the pi-package discovery surfaces (manifest + /better-harness prompt template). This aligns with the repo’s host-boundary approach where host differences live in the adapter matrix, configured-asset providers, session adapters, and output modes.

Changes:

Add Pi session evidence adapter (--platform pi) with JSONL v3 parsing and workspace scoping.
Add Pi configured-asset inventory provider and wire pi into harness/evidence-bundle/task-loop/report CLI surfaces.
Ship a pi manifest + prompts/ template in the npm package; update docs/README/changelog and add tests.

Reviewed changes

Copilot reviewed 49 out of 49 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
test/session-analysis-providers.test.mjs	Adds Pi analyzer coverage and Pi transcript fixtures.
test/scripts-refactor-contract.test.mjs	Updates frozen CLI output hashes after new platform.
test/plugin-manifests.test.mjs	Verifies `package.json.pi` and `prompts/` packaging rules.
test/fixtures/scripts-refactor-contract/session-help.txt	Updates help fixture to include `pi`.
test/fixtures/scripts-refactor-contract/root-help.txt	Updates root help fixture to mention Pi.
test/coding-agent-platform-notes.test.mjs	Ensures sessions diagnostics notes include Pi paths.
test/better-harness-evidence-bundle.test.mjs	Adds Pi agentCustomize lane routing test.
test/agent-customize.test.mjs	Adds Pi inventory/provider tests and fixtures.
test/agent-customize-architecture.test.mjs	Updates architecture doc expectations for “six metadata roots”.
test/agent-asset-baseline.test.mjs	Adds Pi asset baseline fixture test.
scripts/session-analysis/usage-summary.mjs	Extends `--platform` usage to include `pi`.
scripts/session-analysis/selection-profile.mjs	Extends `--platform` usage to include `pi`.
scripts/session-analysis/platforms/pi.mjs	Implements Pi session discovery + normalization (new).
scripts/session-analysis/lifecycle-demand-signals.mjs	Allows `pi` in host-safe normalization.
scripts/session-analysis/analyzer.mjs	Wires Pi platform loader + help strings.
scripts/session-analysis.mjs	Wires Pi platform loader + help strings (shim).
scripts/npm-package/verify-pack.mjs	Requires prompt template in package and forbids it in runtime bundle.
scripts/harness-analysis/task-loop-source.mjs	Accepts `pi` platform; threads `pi-home` through evidence collection.
scripts/harness-analysis/task-loop-report.mjs	Recognizes `pi` in platform selection.
scripts/harness-analysis/report-run.mjs	Accepts `pi` and `--pi-home` for report runs.
scripts/harness-analysis/report-quality.mjs	Adds Pi to session-scope detection patterns.
scripts/harness-analysis/evidence-bundle/contract.mjs	Adds `pi` to allowed providers.
scripts/harness-analysis/evidence-bundle/cli.mjs	Accepts `--pi-home` and `pi` platform.
scripts/harness-analysis/evidence-bundle/agent-customize.mjs	Enables Pi for agentCustomize lane.
scripts/coding-agent-practices/inventory.mjs	Accepts `pi` and includes `piHome` in scope.
scripts/coding-agent-practices/asset-integrity.mjs	Accepts `pi` provider.
scripts/coding-agent-practices/asset-baseline.mjs	Accepts `pi` provider.
scripts/better-harness-cli/registry.mjs	Updates session-analysis command summary to include Pi.
scripts/agent-lint/cli.mjs	Allows `--provider ...
scripts/agent-customize/providers/pi.mjs	Implements Pi configured-asset inventory (new).
scripts/agent-customize/providers/index.mjs	Registers Pi provider collector.
scripts/agent-customize/cli.mjs	Threads `--pi-home` through CLI.
references/session-evidence/sessions-diagnostics.md	Adds Pi platform notes for session evidence diagnostics.
references/agent-customize/routing.md	Adds Pi asset routing guidance.
references/agent-customize/README.md	Adds Pi platform notes link.
references/agent-customize/platforms/pi.md	Adds Pi operating-practice reference (new).
README.zh-CN.md	Documents Pi installation and report usage (zh-CN).
README.md	Documents Pi installation and report usage (en).
prompts/better-harness.md	Adds `/better-harness` prompt template (new).
package.json	Adds `pi` manifest + `pi-package` keyword + ships `prompts/`.
docs/i18n/zh-Hans/docusaurus-plugin-content-docs/current/hosts/adapter-matrix.md	Adds Pi to host adapter matrix (zh-Hans).
docs/glossary.md	Updates session-analysis + host shell glossary entries for Pi.
docs/docs/hosts/adapter-matrix.md	Adds Pi to host adapter matrix (en docs site).
docs/concepts.md	Updates session-evidence concept to include Pi.
docs/community.md	Updates “host shell and packaging” to include Pi manifest.
docs/ARCHITECTURE.md	Updates “five” → “six” plugin metadata roots wording.
docs/adrs/directory-structure.md	Updates platform adapter list and packaging roots count.
docs/adapters/README.md	Adds Pi row and discovery/evidence notes.
CHANGELOG.md	Records Pi host support under Unreleased.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

phodal

I ran an isolated native smoke with @earendil-works/pi-coding-agent@0.83.0 and compared Pi's own resolver/session behavior with this adapter.

What already works:

pi install / pi list accepts this package.
Pi's DefaultPackageManager resolves exactly the canonical better-harness Skill and prompt from the package manifest.
npm run check passes locally: 874/874 tests plus pack verification.

There are still native-contract blockers in the inline comments below. In addition, please update the branch before merge:

Rebase onto current main, which now includes PR #22 and PR #23. At this head, git merge-tree reports 37 content conflicts. Resolve host registries as a union so Copilot support is retained while Pi is added.
Add a dated Pi host spec under docs/specs/ with stable acceptance IDs, and link the new Coding Agent contribution guide. The guide links PR #6 and PR #22 as reviewed examples.
Amend the commit with the required single Co-authored-by line.
Re-run CI after updating the head. The current run is action_required with no jobs, so it is not green CI.

One environment note: the local suite ran under Node 26, outside the repository's declared Node range. The passing local suite is useful evidence but should not replace CI on a supported runtime.

Add Pi (pi.dev / @earendil-works/pi-coding-agent) as an analysis-capable source-local host, following the host contribution guide and the Qwen Code / GitHub Copilot host template. Native contracts were verified against @earendil-works/pi-coding-agent; a dated spec lives at docs/specs/2026-07-30-pi-host-support.md (pi-host-support) with stable PHS-AC acceptance ids. - Distribution shell: `pi` manifest in package.json plus a /better-harness prompt template, so `pi install <repo>` discovers the canonical skills/ root and registers the slash command. Pi reuses the existing package.json, so the package still ships six host metadata roots and the Qoder runtime bundle stays Qoder-only. - Configured assets: scripts/agent-customize/providers/pi.mjs inventories settings-declared pi packages, extensions, skills, prompt templates, and AGENTS.md context. It honors Pi's effective state -- autoload:false fails closed, and per-resource allowlists, `!` exclusions, and `+`/`-` overrides narrow reported resources -- and models piHome and the real user home independently so ~/.agents/skills is found under a relocated PI_CODING_AGENT_DIR. - Session evidence: scripts/session-analysis/platforms/pi.mjs reads workspace-matching JSONL v3 transcripts, resolves the session directory as CLI > env > settings > default, treats a custom session directory as the exact flat JSONL directory qualified by the session-header cwd, gates default-tree root existence on a workspace-keyed directory, and keeps partial/malformed usage explicit instead of zero-filling. - Register `pi` across the supported-platform set and --pi-home threading; the A-06 consistency test now covers seven hosts. - Sync the host adapter matrix, site docs (en/zh), references, READMEs, and CHANGELOG; add provider, session, autoload/filter, relocated-home, custom-dir, precedence, usage, and prompt-template expansion tests. Validated with npm run check (896 tests, pack verification) and against real local Pi data. Co-authored-by: QoderAI (Pi) <qoder_ai@qoder.com>

NickyLam · 2026-07-30T07:03:01Z

Thanks for the thorough native smoke and the four blocking findings — all addressed, and the branch is updated for merge.

Inline threads (all resolved):

Session directory contract: custom --session-dir / PI_CODING_AGENT_SESSION_DIR / settings sessionDir are now the exact flat JSONL directory (CLI > env > settings > default), files still qualified by the session-header cwd; the default keeps the --<cwd-slug>-- tree.
Effective package state: object-form entries honor autoload and the [] / positive / ! / +/- filter layering; autoload: false fails closed.
User home: ~/.agents/skills is resolved from the real user home independently of a relocated PI_CODING_AGENT_DIR.
Usage: only finite observed fields are emitted; missing/malformed siblings stay absent.
Source root: default-tree exists now requires a workspace-keyed session directory.
Prompt ${@:-default}: kept as-is (thanks for confirming it), documented in the Pi platform notes with an expansion smoke test.

Branch updates:

Rebased onto current main (now including feat(copilot): add GitHub Copilot as a first-class host platform #22 and docs(agents): add host contribution guide #23). Host registries were resolved as a union, so GitHub Copilot support is retained alongside Pi; the A-06 support-declaration consistency set now covers seven hosts.
Added docs/specs/2026-07-30-pi-host-support.md (pi-host-support) with stable PHS-AC-* acceptance ids, linking the new Coding Agent contribution guide.
Amended the commit with the required single Co-authored-by line.
Force-pushed the rebased head, which should re-trigger CI.

Local verification on this head: npm run check (896 tests + pack verification) and node --test test/doc-link-graph.test.mjs pass. Point taken on the Node range — the local suite ran under a newer Node than the declared >=22.20.0 <25.0.0, so CI on a supported runner remains the source of truth. Fixes were also exercised against real local Pi data (custom-dir discovery, autoload/filter effective state, relocated-agent-dir ~/.agents/skills, and a complete --platform pi evidence bundle).

Resolve PR QoderAI#25 against the current public-host entrypoint contract while keeping Pi as an analysis-capable source-local host outside the public Quickstart set until an end-to-end interactive report render is observed. The integration review hardens normalized package identity and effective resource filters, session-header and workspace isolation, relative session roots, provider-home propagation, prompt frontmatter, and canonical HTML report routing. It also keeps the six filesystem metadata roots distinct from Pi's package.json manifest. Validated with npm run check (913 tests plus package verification), the documentation link graph, focused Pi provider tests, git diff --check, and pack verification from a materialized staged index. Co-authored-by: Codex (GPT 5.6 Sol) <codex@openai.com>

phodal · 2026-07-30T08:20:55Z

Maintainer review follow-up:

Resolved the conflicts against the current public Quickstart contract.
Hardened Pi package identity/delta handling and session-header validation using Pi v0.83 contracts.
Propagated --pi-home through selection/task-loop paths, corrected report routing ownership, and refreshed the traceability spec/tests.
Validation: local npm run check (913/913 tests plus package verification), materialized-index package verification, and GitHub CI on Ubuntu Node 22/24, macOS Node 22, and Windows Node 22 all passed.

The interactive Pi report-render smoke remains explicitly Unobserved and is not claimed by this merge.

phodal requested a review from Copilot July 30, 2026 02:43

Copilot started reviewing on behalf of phodal July 30, 2026 02:43 View session

Copilot AI reviewed Jul 30, 2026

View reviewed changes

Comment thread scripts/session-analysis/platforms/pi.mjs

Comment thread prompts/better-harness.md

phodal reviewed Jul 30, 2026

View reviewed changes

Comment thread scripts/session-analysis/platforms/pi.mjs Outdated

Comment thread scripts/agent-customize/providers/pi.mjs Outdated

Comment thread scripts/agent-customize/providers/pi.mjs Outdated

Comment thread scripts/session-analysis/platforms/pi.mjs Outdated

NickyLam mentioned this pull request Jul 30, 2026

feat(hosts): add WorkBuddy coding agent host adapter NickyLam/better-harness#1

Closed

NickyLam force-pushed the feat/pi-host-adapter branch from 430f214 to af5a6c6 Compare July 30, 2026 06:59

phodal merged commit 8cf4709 into QoderAI:main Jul 30, 2026
4 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(hosts): add Pi coding agent host adapter - #25

feat(hosts): add Pi coding agent host adapter#25
phodal merged 2 commits into
QoderAI:mainfrom
NickyLam:feat/pi-host-adapter

NickyLam commented Jul 30, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

phodal left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

NickyLam commented Jul 30, 2026

Uh oh!

phodal commented Jul 30, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

NickyLam commented Jul 30, 2026

Summary

Why

Traceability and Scope

Change Type

Test and Review Evidence

Risk and Recovery

AI Involvement

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

phodal left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

NickyLam commented Jul 30, 2026

Uh oh!

phodal commented Jul 30, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants